pm: honor NUB_CACHE_DIR for the engine cache, and report the env tier in nub config - #740

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Reviewed changes — full initial review of the single commit on cachedir-env-654.

• resolved_cache_dir reads the host cache knob first — settings_context.rs returns config_env("CACHE_DIR") (NUB_CACHE_DIR under nub, AUBE_CACHE_DIR standalone) ahead of the settings chain, so the override reaches the packument caches and the global virtual store rather than only the resolver primer.
• config get / config list gained the env tier — read_merged appends read_env_entries(), so the command reports the value the install will actually use instead of undefined.
• env_source provenance helper — env_alias_hit is factored out of raw_from_env so the reporter and the resolver walk the same alias order under the same brand gate.
• is_config_env_alias allow-list — only npm_config_* / NPM_CONFIG_* / pnpm_config_* / PNPM_CONFIG_* and the embedder's own prefix read as configuration; ambient vars (CI, both spellings of the proxy vars) do not.
• primary_entry_key hoisted from list.rs::primary_list_key into config/mod.rs so env entries key the same way file entries do.
• New pm_env_matrix integration test — four behavioral rows through the real binary, each with a negative control, using cache list as the read-side proof of which directory resolved.
• Docs and comments — a new cache-directory section in the install docs, plus corrections to four stale comments that described the removed set_cache_root seam and the long-gone .npmrc-only gate.

I verified the two load-bearing claims in the new comments independently: cacheDir declares sources.cli = [] and carries no managedPolicy, so the early return neither inverts a CLI tier nor skips an enforcement pass; and AUBE_CACHE_DIR already sat first in the reversed alias walk, so standalone aube's precedence is genuinely preserved. config set / delete / explain, protected-key redaction, and --all default-marking are all unaffected by the read_merged change.

ℹ️ Documenting NUB_CACHE_DIR on the site is a brand-boundary decision, not just a doc addition

The install docs now publish NUB_CACHE_DIR and list it above the neutral npm_config_cache_dir. wiki/agents.md sanctions the knob's existence, but the brand-boundary section in the same file says "never a brand env var as a documented USER knob" and prefers neutral spellings on user-facing surfaces. The PR resolves that tension in favour of publishing, which is defensible — the wiki line it edits already claimed the knob was publicly documented — but it is the maintainer's call rather than a consequence of the bug fix.

# Publishing a `NUB_*` knob as documented user surface

## Affected sites
- `site/content/docs/install/index.mdx:604-607` — `NUB_CACHE_DIR` listed first, `npm_config_cache_dir` second.
- `wiki/agents.md:396` — edited to record that `NUB_CACHE_DIR` is now documented and the other two knobs are not.
- `wiki/agents.md` brand-boundary section — "Internal `NUB_*` env vars are fine; never a brand env var as a documented USER knob."

## Required outcome
- A deliberate answer to: does Nub publish `NUB_CACHE_DIR` as supported user surface, or keep it live-but-undocumented and publish only the neutral `npm_config_cache_dir` spelling?

## Suggested approach (optional)
- If publishing: lead the docs block with the neutral `npm_config_cache_dir` and present `NUB_CACHE_DIR` as the Nub-branded equivalent, matching the stated preference for neutral names.
- If not: drop the `NUB_CACHE_DIR` line from the mdx and leave the `wiki/agents.md` correction, which is accurate either way.

## Open questions for the human
- The `resolved_cache_dir` fix is orthogonal to this and should land regardless.

ℹ️ Nitpicks

• site/content/docs/install/index.mdx:616 — "split them and every install degrades to a per-file copy" holds only while the global virtual store is enabled. enableGlobalVirtualStore is off under CI, and a CI cache mount is one of the two motivating examples on this page. The settings.toml cacheDir docs carry the qualifier ("on installs with the global virtual store enabled"); the mdx drops it.
• vendor/aube/crates/aube/src/commands/settings_context.rs:527-529 — the comment correctly notes that a cacheDir that grows a managedPolicy must not be short-circuited here, but nothing enforces it. A debug_assert! on meta.managed_policy.is_empty() would turn the note into a tripwire, if that feels proportionate.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

ℹ️ No critical issues — one minor suggestion inline.

Reviewed changes — the delta since the 79656035 review, which is the single follow-up commit fb98c351. It takes every point from the prior review; all four inline threads are resolved.

• pm_env_matrix::run is now isolated from host config — HOME, USERPROFILE and XDG_CONFIG_HOME are pinned to a fixture-owned home/, and both userconfig spellings joined SCRUBBED. aube_store::dirs::cache_dir() consults XDG_CACHE_HOME ahead of the %LOCALAPPDATA% branch on every platform, so the existing cache pin holds on Windows as well.
• Added both_cache_dir_spellings_agree_across_surfaces — sets NUB_CACHE_DIR and npm_config_cache_dir to two differently-seeded directories and asserts cache list and config get cache-dir both name the branded one. This is a real test rather than a tautology: config get resolves through read_merged, a code path independent of resolved_cache_dir, so inverting either encoding of the precedence rule turns it red.
• debug_assert! guarding the early return — meta::find("cacheDir").is_none_or(|m| m.managed_policy.is_empty()). cacheDir declares no managedPolicy in settings.toml, and SettingMeta::managed_policy is a &'static str, so the assert holds today and fires the moment the setting grows a policy the early return would skip.
• TUI detail pane relabeled Effective value: — the merged read now spans the env tier, so the old .npmrc wording named the wrong source.
• Install docs corrected — the neutral npm_config_cache_dir now leads the env pair, the cross-volume warning is scoped to installs with the shared virtual store on (which settings.toml confirms is off under CI), and the global-links registry joins the list of caches that stay at the platform default.

I re-verified the load-bearing claims in the new copy against the code rather than the prior review: global_links_dir() is cache_dir().join("global-links") off the platform default, so it genuinely does not follow a cacheDir override; and enableGlobalVirtualStore is documented as on outside CI and off under it.

ℹ️ Nitpicks

• vendor/aube/crates/aube-settings/settings.toml:2874-2876 — the cacheDir setting's own docs still list three caches that stay at the platform default (OSV mirror, node-gyp, git clones). That is the same list the mdx just gained a fourth entry for, and it is the copy nub config and the TUI render, so the two surfaces now disagree.
• vendor/aube/crates/aube/src/commands/config/tui.rs:454 — the local npmrc_effective kept its name after the label became Effective value:, which reads slightly against the new comment directly below it explaining that the value routinely comes from no file.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

ℹ️ No critical issues — one minor consistency nit inline.

Reviewed changes — the delta since the fb98c351 review, which is the single follow-up commit 96567771. It takes all three accuracy points from that round; the one inline thread is resolved.

• SCRUBBED gained the npmrc path-redirect family — npm_config_prefix / NPM_CONFIG_PREFIX / PREFIX plus the globalconfig and builtin_config spellings, with the rewritten doc comment naming resolve_global_npmrc_paths as the reason. That makes run()'s "every config root is pinned" claim exact.
• cacheDir's own docs name the global-links registry — settings.toml now lists four caches that stay at the platform default, matching the list the install docs gained last round.
• TUI local renamed to effective — follows the Effective value: relabel and the comment below it explaining the value routinely comes from no file.

I checked the two load-bearing claims against the code rather than the commit message. resolve_global_npmrc_paths (aube-registry/src/config/load.rs:948-973) reads exactly the seven variables now scrubbed and nothing else, so the family is complete rather than merely longer. global_links_dir() is cache_dir().join("global-links") (aube-store/src/dirs.rs:20) with no cacheDir consultation, so it genuinely belongs on the stays-put list.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}